feat: streaming support #248

kwasniew · 2025-08-05T10:10:11Z

About the changes

Adding SSE streaming client support in this SDK similar to Node SDK.

When starting the SDK we can set the experimental mode to be streaming instead of default polling mode
I manually tested that disconnects are handled gracefully (this should be also tested in the SSE client itself)
Added tests showing how streaming works from this SDK perspective
Under the hood streaming events are handled by the yggdrasil engine so we don't need to test all the details as in the Node SDK
JRuby doesn't have support for one of the SSE client transitive dependencies so it falls back to polling
Also we don't store state to a backup file for now in streaming mode. It will be added once yggdrasil can expose full state to the SDKs

Important files

Discussion points

kwasniew · 2025-08-05T10:10:58Z

examples/simple.rb

 @unleash = Unleash::Client.new(
-  url: 'https://unleash.herokuapp.com/api',
-  custom_http_headers: { 'Authorization': '943ca9171e2c884c545c5d82417a655fb77cec970cc3b78a8ff87f4406b495d0' },
+  url: 'https://app.unleash-hosted.com/demo/api',


re-using sdk-examples setup https://github.com/Unleash/unleash-sdk-examples/blob/main/Ruby/.env.example as heroku is deprecated

kwasniew · 2025-08-05T10:14:19Z

lib/unleash/client.rb

      Unleash.engine.register_custom_strategies(Unleash.configuration.strategies.custom_strategies)

-      Unleash.toggle_fetcher = Unleash::ToggleFetcher.new Unleash.engine
+      Unleash.toggle_fetcher = Unleash::ToggleFetcher.new Unleash.engine unless Unleash.configuration.streaming_mode?


fetcher makes initial HTTP call on instance creation. We don't want that for how with streaming to avoid cross locks between streaming client and polling client

kwasniew · 2025-08-05T10:16:13Z

lib/unleash/configuration.rb

      :bootstrap_config,
      :strategies,
-      :use_delta_api
+      :use_delta_api,


we should deprecate this property as we have a standardized experimental mode in Node SDK that is either {type: 'streaming'} or {type: 'polling', format: 'delta'} or {type: 'polling', format: 'full'}

I don't think having a standard with interface between language and SDK is too important here, most of the SDKs provide interfaces that are comfortable in that language.

I do agree that we should deprecate this and use your pattern though

kwasniew · 2025-08-05T10:17:28Z

lib/unleash/streaming_client.rb

+        self.toggle_engine.take_state(event.data)
+      end
+
+      # TODO: update backup file


state engine needs to expose current state so we can save it . Both streaming and polling with delta will need it

kwasniew · 2025-08-05T10:31:05Z

examples/streaming.rb

+puts ">> START streaming.rb"
+
+@unleash = Unleash::Client.new(
+  url: 'https://app.unleash-hosted.com/demo/api',


demo doesn't have streaming enabled so this needs to be changed to enterprise URL

kwasniew · 2025-08-05T13:55:53Z

unleash-client.gemspec

  spec.require_paths = ["lib"]
  spec.required_ruby_version = ">= 2.7"

+  spec.add_dependency "ld-eventsource", "2.2.4" unless RUBY_ENGINE == 'jruby'


SSE client has http dependency that doesn't work with jruby

kwasniew · 2025-08-05T13:56:08Z

spec/unleash/client_spec.rb

    ).to be false
  end
+
+  unless RUBY_ENGINE == 'jruby'


run those tests for non jruby platforms

kwasniew · 2025-08-05T13:56:35Z

lib/unleash/util/event_source_wrapper.rb

+        return nil if RUBY_ENGINE == 'jruby'
+
+        begin
+          require 'ld-eventsource'


don't let this dependency spread throughout the code

coveralls · 2025-08-05T14:03:51Z

Pull Request Test Coverage Report for Build 16880273865

Details

95 of 109 (87.16%) changed or added relevant lines in 5 files are covered.
1 unchanged line in 1 file lost coverage.
Overall coverage decreased (-1.1%) to 94.32%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
lib/unleash/configuration.rb	13	14	92.86%
lib/unleash/util/event_source_wrapper.rb	7	9	77.78%
lib/unleash/streaming_client_executor.rb	41	45	91.11%
lib/unleash/streaming_event_processor.rb	22	29	75.86%

Files with Coverage Reduction	New Missed Lines	%
lib/unleash/configuration.rb	1	96.7%

Totals
Change from base Build 16671337925:	-1.1%
Covered Lines:	548
Relevant Lines:	581

💛 - Coveralls

kwasniew · 2025-08-05T14:12:51Z

lib/unleash/streaming_client.rb

+    end
+
+    def start
+      self.mutex.synchronize do


similar synchronization pattern to toggle_fetcher so that we guard running property

Why do we need to guard running? That should only ever be a problem if two threads are calling start and stop on the same instance in quick succession, surely?

No mutex needed in the scheduler for SSEs - lifecycle methods called from single thread. But in the event processor event processing happens from EventSource background threads that could potentially be concurrent so keeping it there

sighphyre

Cool! Come grab me next week and we can beat Yggdrasil into shape so you can finish this off!

sighphyre · 2025-08-08T11:58:26Z

lib/unleash/configuration.rb

      :bootstrap_config,
      :strategies,
-      :use_delta_api
+      :use_delta_api,


I don't think having a standard with interface between language and SDK is too important here, most of the SDKs provide interfaces that are comfortable in that language.

I do agree that we should deprecate this and use your pattern though

sighphyre · 2025-08-08T12:01:23Z

lib/unleash/configuration.rb

    end

+    def streaming_mode?
+      return false if RUBY_ENGINE == 'jruby'


I think we should consider raising an exception here or logging an error. I would be very annoyed if an SDK I used didn't do what I told it and quietly did something different

sighphyre · 2025-08-08T12:24:55Z

lib/unleash/streaming_client.rb

+    end
+
+    def start
+      self.mutex.synchronize do


Why do we need to guard running? That should only ever be a problem if two threads are calling start and stop on the same instance in quick succession, surely?

sighphyre · 2025-08-08T12:39:41Z

lib/unleash/client.rb

@@ -1,15 +1,17 @@
 require 'unleash/configuration'
 require 'unleash/toggle_fetcher'


I feel like there's a missing somewhere here and I think that's related to the difference between the toggle fetcher internals and LD's event source lib. The toggle fetching code splits the logic for fetching toggles and the concurrency responsibility into two classes, whereas with the event source lib it's a single entity. This means we can't treat them like interchangable ducks and I really think we should be able to do that. It feels very wrong to have a :streaming_client and :fetcher_scheduled_executor exposed as accesors when we can only ever have one of these and they do the same job in different ways. It's leading to a bunch of places in this PR where we're checking which we and making local decisions. If we created something like a fetch_client that composed of both the toggle_fetcher and scheduled_executor which exposes start and stop methods we could make a lot of that go away

the root cause is who's driving the new updates: scheduler or streaming client handler. I will play around with a different split of responsibilities (as I did in the Java SDK) on Monday but I'm not sure we can have a drop-in replacement here

You comment was spot on. Thank you for that. I managed to create streaming_client_executor and streaming_event_processor. streaming_client_executor can play a role of a fetcher_scheduled_executor (kept the same field name in attr jus tin case someone depends on it). Please let me know if you like it more now

sighphyre · 2025-08-08T12:44:34Z

lib/unleash/util/event_source_wrapper.rb

+module Unleash
+  module Util
+    module EventSourceWrapper
+      def self.client


Hmm, I'm a bit tempted to fail hard here rather than fall back to polling. I'm kinda okay with errors that happen on startup and I think it's better to force folks to set their stuff up correctly. We can always relax it later but if we do this now, I doubt we can enforce it later

sighphyre

Looking awesome. Gonna be great to get this one done!

thomasheartman added this to Issues and PRs Aug 5, 2025

github-project-automation bot moved this to New in Issues and PRs Aug 5, 2025

kwasniew commented Aug 5, 2025

View reviewed changes

feat: streaming support

7fb2b86

kwasniew force-pushed the streaming-support branch from 368230d to 7fb2b86 Compare August 5, 2025 10:13

kwasniew commented Aug 5, 2025

View reviewed changes

kwasniew added 7 commits August 5, 2025 14:00

test: streaming client

d52542a

test: streaming client fix for jruby

739a856

feat: jruby falls back to polling

237e448

feat: jruby falls back to polling

c9c842b

feat: jruby falls back to polling

8c26899

feat: jruby falls back to polling

c92cd91

feat: jruby falls back to polling

0ca130f

kwasniew commented Aug 5, 2025

View reviewed changes

spec/unleash/client_spec.rb

).to be false

end

unless RUBY_ENGINE == 'jruby'

Copy link

Contributor Author

kwasniew Aug 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

run those tests for non jruby platforms

kwasniew commented Aug 5, 2025

View reviewed changes

refactor: remove mutable state

4bc41ee

refactor: simplify mode selection

84ce97e

kwasniew commented Aug 5, 2025

View reviewed changes

kwasniew requested review from FredrikOseberg and sighphyre August 6, 2025 07:20

ivarconr moved this from New to In Progress in Issues and PRs Aug 6, 2025

fix: event format in spec

4886cb7

sighphyre reviewed Aug 8, 2025

View reviewed changes

kwasniew added 2 commits August 11, 2025 13:58

refactor: apply PR feedback about duck typed client code

019ddec

feat: fail hard on no sse client

c85d9f1

kwasniew added 5 commits August 11, 2025 14:07

feat: fail hard on sse with jruby

7b8b8d6

refactor: remove unnecessary mutex

623b9dd

chore: fix linting errors

0fdba09

chore: fix linting errors

0a0ab35

chore: consistent logging

da360d1

sighphyre approved these changes Aug 11, 2025

View reviewed changes

github-project-automation bot moved this from In Progress to Approved PRs in Issues and PRs Aug 11, 2025

kwasniew merged commit 0f21509 into main Aug 11, 2025
44 checks passed

kwasniew deleted the streaming-support branch August 11, 2025 13:09

github-project-automation bot moved this from Approved PRs to Done in Issues and PRs Aug 11, 2025

		@@ -1,15 +1,17 @@
		require 'unleash/configuration'
		require 'unleash/toggle_fetcher'

feat: streaming support #248

feat: streaming support #248

Uh oh!

Conversation

kwasniew commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

About the changes

Important files

Discussion points

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coveralls commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 16880273865

Details

💛 - Coveralls

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sighphyre left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sighphyre left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kwasniew commented Aug 5, 2025 •

edited

Loading

coveralls commented Aug 5, 2025 •

edited

Loading